/**
 * Copyright 2006 gworks.com.au
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License. (http://www.apache.org/licenses/LICENSE-2.0)
 *
 * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed 
 * on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for 
 * the specific language governing permissions and limitations under the License.
 *
 * <dhamma-message src="Atisha (11th century Tibetan Buddhist master)">
 * 	The greatest achievement is selflessness. The greatest worth is self-mastery.
 * 	The greatest quality is seeking to serve others. The greatest precept is continual awareness.
 * 	The greatest medicine is the emptiness of everything. The greatest action is not conforming with the worlds ways.
 * 	The greatest magic is transmuting the passions. The greatest generosity is non-attachment.
 * 	The greatest goodness is a peaceful mind. The greatest patience is humility.
 * 	The greatest effort is not concerned with results. The greatest meditation is a mind that lets go.
 * 	The greatest wisdom is seeing through appearances. 
 * </dhamma-message>
 */
package org.javaongems.client;

import java.util.Map;

/**
 * <p>Provide the common scaffoldings of a coordinator which wire the browser, 
 * Gemlet and the controllers together.</p>
 * <p>Responsibilities:
 * <ul>
 * 	<li>delegate all application specific coupling to the Gemlet
 * 	<li>manage the relationship between the application (ie. cohesive 
 * 			controller set) and the browser container
 * 	<li>handle the browser's navigation (ie. back/forward) history
 * 	<li>build the command history as controllers transition states 
 * 	<li>query gem properties that were bootstrapped to the entry points' page 
 * 	<li>act as the common enviroment to report/log messages to
 * </ul>
 * </p>
 * <p>Collaborators:
 * <ul>
 * 	<li> Gem - whose global stone variable is an instance of the coordinator
 * 	<li> Gemlet - who handles all application specific behavior
 * 	<li> Controllers - who manage specific functional areas of the application
 * 	<li> Commands - to instruct them to do undo() and redo() actions 
 * </ul>
 * </p>
 * @see org.javaongems.client.Gem#stone
 * @see org.javaongems.client.Gemlet
 * @see org.javaongems.client.Controller
 * @see org.javaongems.client.Command
 * 
 * @author Ashin Wimalajeewa (ash)
 */
public interface Coordinator extends Gemlet {
	/**
	 * Command that sends the undo() signal to the appropriate Command object. It is 
	 * invoked when the browser's back button functionality is initiated or a 
	 * piece of javascript executes "history.go(-1)".
	 * 
	 * @see #onTransition(Command)
	 * @see #forward()
	 */
	public void back();

	/**
	 * Command that sends the redo() signal to the appropriate Command object. It is 
	 * invoked when the browser's forward button functionality is initiated or a 
	 * piece of javascript executes "history.go(1)". 
	 * 
	 * @see #onTransition(Command)
	 * @see #back()
	 */
	public void forward();
	
	/**
	 * Command that builds the command history to support the browser's back/forward features.
	 * Invoked by either a controller or command when the command's execute()
	 * method is completed.
	 * @param cmd - Command that was executed and that supports undo/redo functionality
	 * 
	 * @see #back()
	 * @see #forward()
	 */
	public void	onTransition(Command cmd);
	
	/**
	 * Command that adds/updates the active controller list with the given controller.
	 * Typically invoked by a controller during its setUp() method.
	 * 
	 * @param openedCtrlr - the controller that was just setup/reactivated 
	 * 
	 * @see #closeController(Controller)
	 */
	public void openController(Controller openedCtrlr);

	/**
	 * Command that removes the given controller from the active controller list.
	 * Typically invoked by a controller during its tearDown() method.
	 * 
	 * @param closedCtrlr - the controller that was just torn down
	 * 
	 * @see #openController(Controller)
	 */
	public void closeController(Controller closedCtrlr);

	/**
	 * Query the cargo associated with the coordinator. Remember, that there is
	 * only one coordinator which is represented by the "stone" variable. This
	 * means that this is globally accessible cargo. 
	 * @return the cargo (user-defined baggage) that is pinned to the
	 * coordinator.
	 */
	public Map getCargo();
	
	/**
	 * Query gem properties were serialised into entry points' page that
	 * GWT bootstraps from. This method should delegate to the
	 * Gemlet's getGemProperty() method and then attempt to cast the
	 * value as String and return it or the default value.
	 * 
	 * @param prop - name of the property to query
	 * @param defVal - the default value to return if the real value is null
	 * @return - either the non-null value associated with the property or the
	 * default value
	 * 
	 * @see EntryPointPage
	 * @see Gemlet#getGemProperty(String)
	 */
	public String getGemPropertyAsString(String prop, String defVal);
	
	/**
	 * Command that logs a message. The Gemlet establishes a relationship with 
	 * a loggable device. This method is a convenience method that delegates to 
	 * the Gemlet. 
	 * @param msg - the message to log
	 * 
	 * @see Gemlet#log(String, Throwable)
	 */
	public void log(String msg);
	
	/**
	 * Command that causes the browser to load the specified url.
	 * 
	 * @param url - fully qualified url, or uri or relative reference
	 */
	public void openUrl(String url);
	
	/**
	 * Query that returns the application image context based on the application 
	 * context.
	 * @return - location of where common images can be found for the application
	 * 
	 * @see Gemlet#getApplCtx()
	 */
	public String getApplImageCtx();
	
	/**
	 * Query that returns the location of the blank image. Blank images are 
	 * currently required to support transpareny in PNG files for IE.
	 * @return - location of where the "blank.gif" image is.
	 * 
	 * @see #getApplImageCtx()
	 */
	public String getBlankImageUri();
	
	/**
	 * Query that returns the fully Gems RPC context with the service name.
	 * @param serviceName - the logical name of the service
	 * @return the end point to use with ServiceDefTarget
	 */
	public String getEndpointForService(String serviceName);
}
